Layout automation with python¶
Thomas Ferreira de Lima¶
Lightwave Lab, Princeton University
Oct 31st, 2019
https://github.com/thomaslima/2019-siepic-workshop-zeropdk
Email: tlima@princeton.edu
Outline¶
- Motivation for procedural layout
- Basic definitions
- Tool requirements
- KLayout
- Python/Docker
- An overview of Zeropdk
- Demo preparation
- Using SiEPIC with Zeropdk
- Demo 1: Using SiEPIC cell library
- Hierarchical layout
- Demo 2: MZI PCell
- Advanced layout techniques:
- Geometry unit testing (lytest)
- Visual debugging (lyipc)
- Version control and collaboration
- Outlook (help needed with DRC, SiEPIC and docs)
Motivation for procedural layout¶
- GDSII is the industry standard file format for IC layout.
- It organizes geometry in polygons, cells, and cell references.
- However, it is quasi-binary: understood by machines, useless to humans.
- There is no support for parameters, design intent, comments, connectivity, physical data.
- Poor representation of curves
GDS has problems with curves¶
GDS does not capture logical relation¶
Procedural vs. Computer-aided¶
Computer-aided layout
- Interactive: designer sees what’s happening at all times
- Intuitive
- No software bugs
- Macros: some benefits of procedural
Procedural layout
- Completely repeatable
- Easy to apply global changes
- Easy to version a chip, not just a library
- Full record of design intent
IC design “by hand”, aided A LOT by computer¶
Difference with macros¶
- Procedural means 100% coded
- Push a button, GDS comes out
- This means entire chips are defined 100% by source code
- repeatable
- human understandable
- arbitrarily complex
- more easily version controlled
Example from one of our chips¶
# make_chip.py
FLOORPLAN_SAFE = 50
TECHNOLOGY = TECHNOLOGY.layers # TODO refactor
if __name__ == "__main__":
layout = pya.Layout()
dbu = layout.dbu = 0.001
TOP = layout.create_cell("TOP")
origin = pya.DPoint(0, 0)
ex = pya.DVector(1, 0)
ey = rotate90(ex)
# FLOORPLAN
FX, FY = 7850, 3000 # um
layout_box(TOP, layout.layer(TECHNOLOGY["FloorPlan"]),
origin, origin + FX * ex + FY * ey, ex)
# Placing each experiment
placement_list = {
"FeedbackWeightBank_experiment": (
exp.FeedbackWeightBank_experiment, # PCell class
2792.04000, 328.87000, # position
{"angle_ex": 90, "N": 5}, # parameters
),
# ...
}
# Place all PCells in placement_list and export port locations for routing
for name, (klass, x, y, params) in placement_list.items():
exp_ports[name] = klass(name, params=params).place_cell(
TOP, x * ex + y * ey
)
# ...
# Perform routing using exp_ports dictionary
# ...
# Removing the $$$CONTEXT_INFO$$$ top cell (Foundries don't like it)
save_options = pya.SaveLayoutOptions()
save_options.write_context_info = False
# CMC told us to have maximum cell name length of 60 characters
save_options.gds2_max_cellname_length = 60
layout.write("mpw-chip.gds", save_options)
Basic definitions¶
PCells¶
PCells are the foundation of layouts with more than a couple polygons
- Rule of thumb: one pcell per device
- Defined by code (logic) instead of points (geometry)
- Reused to create many different geometries
- Easy to edit
- Can be nested
Routing elements¶
Routing elements refer to the connections between devices (drawn in PCells). They could be metal traces, optical waveguides, or I/O elements.
Ports¶
The connection between PCells and routing elements are defined in the concept of Ports. The port must contain information on the type of connection, the dimensions of the routing elemenet (e.g. waveguide width), a human-readable name, and positioning.
Tool Requirements¶
- KLayout
- Python modules:
- klayout
- zeropdk
KLayout¶
KLayout scripting¶
You probably all know KLayout, but few people make good use of the scripting documentation:
- klayout.de » Documentation » Programming Scripts (recommend reading Database API and Geometry API)
- klayout.de » Documentation » Reference (have it open while coding)
Python (klayout)¶
I helped Matthias to release a klayout package in PyPI. It works in a standalone way and is loaded with the Database and Geometry APIs, but not Application or Qt (yet).
pip install klayout
Currently there are pre-built wheels in the following versions:
| OS | Python Version |
|---|---|
| macOS 10.11+ | 2.7, 3.7 |
| macOS 10.13+ | 3.5, 3.6 |
| linux x64, x32 | 2.7, 3.5, 3.6, 3.6 |
| win32, win64 | 3.5, 3.6, 3.7 |
Note for advanced users: You can attempt to build klayout from source by running python setup.py install on the cloned folder from klayout's github repo.
!pip install klayout
import klayout.db as pya
a = pya.DPoint(1, 2)
b = pya.DVector(0, 1)
a+b
Python (zeropdk)¶
Our lab relies on klayout's database engine to produce masks for MPW manufacturing. To aid collaboration, we open-sourced a tool called zeropdk.
Many foundries only offer PDKs to commercial software with a steep price tag, but are happy to offer libraries of standard components in the .gds format. ZeroPDK allows you to quickly bootstrap a Photonics PDK without necessarily relying on their partners: great for academic users and students. Also great for pro users.
Zeropdk is available with pip install zeropdk and the source code is released in our github page
An overview of Zeropdk¶
- Three submodules:
zeropdk.tech: helps load a tech layer definition from alypfile.zeropdk.layout: a library of tools for advanced polygon creation (round polygons, waveguides, etc).zeropdk.pcell: contains standard class definitions of PCells, ports and parameters. The idea is to make it compatible with SiEPIC-Tools and Klayout Macro Editor (eventually)
- Similarly to SiEPIC-Tools, zeropdk modifies/patches some Python bindings for klayout objects, such as SimplePolygon, Point, Vector.
- Beta status: scarce docs (need help!)
!pip install zeropdk
!ls ../demo | grep .lyp
from zeropdk.tech import Tech
EBeam = Tech.load_from_xml('../demo/EBeam.lyp')
EBeam.layers
import zeropdk.layout.waveguide_rounding as wav_rounding
wav_rounding.main() # produce some interesting non-Manhattan waveguides
Contents of waveguide_rounding.gds:
!python ../demo/main_python.py
# !open example_mask.gds
Demo preparation¶
Two options¶
1. Your custom python installation¶
If you have python 3.6+ installed in your computer and are comfortable with installing packages with pip, all we need is pip install zeropdk.
2. Docker Container¶
For users without Python 3.6+ setup, I have prepared a docker container with all the necessary packages pre-installed. It is compatible with all OS and runs isolated from your installation. I've tested on macOS and Windows 10.
Docker requirements:¶
Windows Requirements:¶
- Windows 10 64-bit: Pro, Enterprise, or Education (Build 15063 or later).
- Hyper-V and Containers Windows features must be enabled.
- The following hardware prerequisites are required to successfully run Client Hyper-V on Windows 10:
- 64 bit processor with Second Level Address Translation (SLAT)
- 4GB system RAM
- BIOS-level hardware virtualization support must be enabled in the BIOS settings. For more information, see Virtualization.
macOS Requirements:¶
Mac hardware must be a 2010 or newer model, with Intel’s hardware support for memory management unit (MMU) virtualization, including Extended Page Tables (EPT) and Unrestricted Mode. You can check to see if your machine has this support by running the following command in a terminal: sysctl kern.hv_support
macOS must be version 10.13 or newer. We recommend upgrading to the latest version of macOS.
- If you experience any issues after upgrading your macOS to version 10.15, you must install the latest version of Docker Desktop to be compatible with this version of macOS.
- At least 4 GB of RAM.
- VirtualBox prior to version 4.3.30 must not be installed as it is not compatible with Docker Desktop.
1. Download Docker:¶
- macOS
- Windows download
- Note: on Windows, the installation will require you to sign out and sign in, so save all your work!
2. Install Docker¶
The first time you start Docker it will pop up a dialog telling you you need an account. You do not need an account. Close the dialog that tells you this: Docker is already running and fully functional. There are thousands of people complaining about the fact that they try to force you to login in order to download/use it.
3. Pull docker image from docker.io¶
Open your command line terminal (cmd in Windows) and type:
docker pull felimath/zeropdk
You can check the Docker Image with
docker images
It should show:
REPOSITORY TAG IMAGE ID CREATED SIZE
felimath/zeropdk latest 1082ad385453 About a minute ago 1.42GB
...This demo's image id: 1082ad385453.
4. Navigate to the demo folder, downloaded from github.¶
Download the demo files from the workshop's github repo and navigate to the demo folder.
(Option 1) Using git:¶
git clone https://github.com/thomaslima/2019-siepic-workshop-zeropdk.git ~/2019-siepic-workshop-zeropdk
If you have cloned the repo, navigate to ~/2019-siepic-workshop-zeropdk/demo with:
cd ~/2019-siepic-workshop-zeropdk/demo
(Option 2) Download zipped file:¶
If you don't have git (Windows, or any other reason), feel free to download a zip file directly from github. In my computer, I extracted to the default location and used the following command to get there:
# windows
cd Downloads\2019-siepic-workshop-zeropdk-master\2019-siepic-workshop-zeropdk-master\demo
# bash (unix)
cd ~/Downloads/2019-siepic-workshop-zeropdk-master/demo
5. Run the jupyter notebook start script.¶
From within the demo folder, run the following command in your console
# windows
start-jupyter-windows.bat
# unix
./start-jupyter-unix.sh
Final step:¶
Open a browser and go to the highlighted address as shown above. In my case, it was http://127.0.0.1:42019/?token=71e68bae28024c9be4382e6a3f3bd03a0394f678a4e4de2c, but yours will have a different token.
Installation Instructions (Advanced)¶
Python 3¶
I write all my scripts using python 3.6+ in mind. I did not pay special attention to backwards compatibility with earlier versions. Fixing syntax bugs should be straightforward if you are experienced with python. If you need to use the packages or demos presented here, feel free to submit a pull request to the relevant repositories.
KLayout¶
KLayout is an open-source viewer and editor of IC layout files. It has a programming interface with Python and Ruby programming lanaguages. Recently, a pip package was released for the following python distributions:
| OS | Python Version |
|---|---|
| macOS 10.11+ | 2.7, 3.7 |
| macOS 10.13+ | 3.5, 3.6 |
| linux x64, x32 | 2.7, 3.5, 3.6, 3.6 |
| win32, win64 | 3.5, 3.6, 3.7 |
Note for advanced users: You can attempt to build klayout from source by running python setup.py install on the cloned folder from klayout's github repo.
Zeropdk¶
Zeropdk is a python opensource package with basic tools for photonics layout based on the klayout database engine. It is akin to SiEPIC-tools but it was written so that it could be compatible with any foundry's layer stacks. It can also be installed with pip via pip install zeropdk. Alternatively, install from source via the github repo. Documentation is scarce at the moment but hopefully this workshop will be a good start.
Meta: Adapting the docker container to your demo¶
If you like Docker and want to build your own Docker image (opensource or closed source), I put the recipe (called Dockerfile) inside the docker-image folder.
Demo 1¶
Open demo/1. Demo - Using SiEPIC cell library.ipynb
Demo 2¶
Open demo/2. Demo - MZI PCell.ipynb
Advanced layout techniques¶
One goal: enable collaboration reduce dependence on a single designer or specific computer setup.
Key questions – recommended tools¶
What is going on? – Visual debugging¶
- Python debugger + inter-process control (github.com/atait/klayout-ipc)
Is it working? – Geometric unit testing¶
- KLayout XOR diff program + Pytest (docs.pytest.org)
What if, oops, and collaborating – Version control¶
- Git (www.atlassian.com/git/tutorials)
What does this thing do? – Documentation & examples¶
- Sphinx (www.sphinx-doc.org)
What parts go where? – Modules, packaging¶
- Read and think about it (docs.python-guide.org/writing/structure)
Procedural Layout introduces pitfalls¶
- Completely repeatable (but opaque and not interactive)
- Press a button, GDS comes out
- Easy to apply global changes (and introduce subtle side-effects)
- Easy to version and collaborate (and quietly break your friends’ stuff)
- Full record of design intent (or messy unreadable code)
Powerpoint presentation in person. Might share here later.